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Running  ROSS  in  an  Emaca  Environment 


1.  Introduetlon 


"y  This  paper  describes  a  software  environment  in  which  to  run  ROSS,  an  object-oriented  simulation 
language^  developed  at  Rand  (MCA82,  KLA82|.  The  goal  of  the  facility  is  to  provide  the  user 
with  tools  that  can  increase  the  speed  at  which  the  user  creates,  tests  and  debugs  large  ROSS  sys¬ 
tems.  Using  ROSS  alone,  making  permanent  fixes  to  code  was  tedious.  The  user  had  to  get  out  of 
ROSS,  into  an  editor,  make  the  changes,  return  to  ROSS,  then  re-load  the  changed  file. 


-Our  approach  is  to  embed  ROSS  inside  Emacs,  a  powerful,  personalizable,  screen-oriented,  editor . 
(hence  we  refer  to  it  as  the  “ROSS-Emacs”  facility).  We  have  tailored  Emacs^to  provide  just  the 
tools  the  ROSS  programmer  needs.  For  example,  the  user  never  has  to  leave  ROSS  to  make  code 
changes,  and  all  the  lower-level  details  of  code  management— such  as  finding  the  file  (and  location 
in  the  file)  of  behaviors  or  functions,  saving  permanent  changes  onto  disk,  and  loading  new 
definitions  back  into  ROSS-are  done  automatically.  This  facility  makes  ROSS  a  much  more 
friendly  and  powerful  environment  for  debugging. 


^7 


begiiKwitb  a  brief 


'  The  uiiinining  srctions  describe  various  facets  of  the  ROSS-Emacs  facility.  ^^begiD>:wi 
overview,  followed  by  descriptions  of  commands  for  editing  functions  and  behaviors,  managing 
Emacs  windows,  evaluating  Lisp  forms,  compiling  Lisp  forms,  and  defining  ROSS  systems.  Each 
section  starts  with  a  brief  description,  followed  by  a  list  of  the  Emacs  commands  that  implement 
the  described  capabilities.  ^  - -  - 


t.  Starting  and  typing  ROSS/Llsp  forms 


In  this  environment,  the  user  is  actually  in  the  Emacs  editor.  ROSS  b  invoked  automatically  as  a 
subprocess  of  Emacs.  The  ROSS  session  has  its  own  buffer,  called  "lisp"  in  an  Emacs  window. 
The  user  types  forms  in  the  window  just  as  he  would  to  ROSS.  When  he  hits  a  <CR>  Emacs 
takes  the  form  just  typed,  submits  it  to  ROSS,  and  prints  the  value  out  on  the  screen.  Thus,  in 
simple  interactions,  the  environment  looks  just  like  it  did  before.  However,  because  you  are  also 
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in  Emacs,  many  new  things  an  possible.  For  example,  in  the  Lisp  (ROSS)  window,  you  may 
move  the  cursor  back  and  forward  across  the  current  line,  or  go  back  to  point  to  previous  lines. 
In  this  way  you  can  even  re-evaluate  expressions  you  submitted  earlier  to  ROSS.  For  example, 
assume  that  10  lines  earlier  in  a  ROSS  session  you  typed  “(setq  foo  5)”  and  now  you  want  foo  to 
have  the  value  6.  Instead  of  typing  a  new  setq,  you  can  just  move  the  cursor  in  the  Lisp  window 
to  the  “5”  in  the  previous  setq,  then  change  the  “5”  to  “O’*  in  the  normal  Emacs  fashion.  Now 
go  to  the  end  of  the  setq  and  hit  <CR>.  Since  Emacs  submits  the  expression  just  prior  to  the 
last  <CR>  to  ROSS,  this  <CR>  this  will  have  the  desired  effect  of  re-evaluating  the  form  and 
setting  foo  to  6.  In  general,  the  ability  to  edit  your  interactive  ROSS  session  will  make  it  much 
easier  to  correct  errors  and  execute  repetitive  actions. 

3.  Enoaea  eommsuidn  for  ROSS  and  Lisp 

A  number  of  new  Emacs  commands  have  been  defined  to  make  things  simpler  when  interacting 
with  ROSS.  Like  normal  Emacs  commands,  they  have  a  name  and  are  often  associated  with  spe¬ 
cial  keystroke  combinations.  But  unlike  other  commands,  they  know  about  ROSS  and  Lisp  struc¬ 
tures  and  actions.  They  not  only  allow  you  to  reference  characters  (primitive  text  structures)  but 
also  to  reference  s-expressions,  function-definitions,  behavior-definitions,  messages  and  objects 
(primitive  ROSS  and  Lisp  structures).  They  not  only  allow  yon  to  move  or  delete  things  (primi¬ 
tive  text  operations)  but  also  to  evaluate,  edit  or  compile  them  (primitive  ROSS  and  Lisp  opera¬ 
tions). 

All  of  the  commands,  whose  operation  will  be  explained  below,  can  either  be  invoked  by  the  keys¬ 
trokes  indicated  in  the  bindings  or  by  using  the  Emacs  ESC-X  prefix.  For  example,  to  evaluate 
the  current  list  you  can  either  say  ESC-e  or  ESC-Xzap-expr;  to  go  to  the  previous  window  you 
can  say  either  ‘X-n  (hitting  the  “CTRL”  and  “x”  keys  simultaneously,  followed  by  the  "n”  key), 
or  use  ESC-Xprevious-window. 


Function 

Bindinn 

Action 

edit-function 

ESC-f 

Prompts  for  a  function  name,  then  goes  to  a  window  with  the  file  where 
this  function  is  contained,  putting  the  cursor  at  the  start  of  the 
definition.  If  Emacs  doesn’t  know  which  file  the  function  is  in,  it  will  ask 
you  for  the  file  name.  It  will  only  have  to  ask  once,  since  it  remembers 
the  name. 

edit- pointed-function 

ESC-g 

Like  edit-function,  except  it  will  edit  the  function  you  are  pointing  at. 
You  should  be  pointing  at  a  function  defining  form  (beginning  with 
“(def.  If  you  are  not  pointing  directly  at  such  a  form,  it  will  search 
backward  for  the  nearest  such  form,  and  edit  that  function. 

edit- behavior 

ESC-b 

Like  edit-function,  only  it  prompts  for  an  object  and  a  behavior  pattern, 
then  goes  to  the  appropriate  file.  In  specifying  the  behavior  pattern  the 
user  need  only  type  enough  of  the  initial  portion  of  the  pattern  to  allow 
unique  identification.  However,  ROSS  pattern  variables  and  “>” 

cannot  be  used. 

edit-pointed  behavior 

ESC-c 

Like  edit-pointed  function,  except  it  applies  to  behaviors.  You  should 
be  pointinx  to  a  behavior  definition;  “(ask  xxx  when  receivinx  . 

ROSS'Emftcs  eommftnds  for  editing 


The  functions  edit-funelion  or  edit-pointed  function  edit  Lisp  function  definitions.  The  former 
prompts  for  a  function  name,  the  latter  assumes  you  are  pointing  at  the  function  definition  you 
intend  to  edit  (which  you  might  be  doing  if  you  had  just  asked  Lisp  to  pretty>print  the  function 
definition),  so  doesn’t  prompt  for  anything.  In  either  case,  if  Emacs  can  find  the  function  (it  may 
prompt  you  for  a  file  name  if  it  has  trouble)  it  will  open  a  new  window  containing  the  file  and  will 
position  the  cursor  at  the  start  of  the  function  definition.  You  can  treat  this  window  as  in  an  or* 
dinary  Emacs  session.  In  particular,  you  can  modify  the  definition,  add  new  functions,  use 
evaluation  commands  (see  Section  6.)  and  then  save  the  file  ('X‘S)  when  you  are  satisfied  with 
the  changes.  At  this  point  you  will  probably  want  to  go  back  to  the  Lisp  window.  You  can  do 
this  in  several  ways  using  standard  Emacs  commands.  These  options  are  discussed  in  the  next 
section. 


To  edit  behaviors  use  the  Emacs  commands  edit-behavior  and  edit-pointed-behavior.  These  are 
perfectly  analogous  to  their  counterparts  for  functions. 


In  searching  through  files,  these  four  functions  must  make  assumptions  about  the  ^ntactic  pat¬ 
terns  normally  associated  with  function  and  behavior  definitions.  Therefore,  if  you  write  your 
functions  and  behaviors  in  non-standard  ways,  these  functions  may  fail  to  find  them.  To  make 
your  life  easier  follow  these  simple  rules: 

•  All  function  and  behavior  definitions  should  be  uniformly  lower-case. 

•  Function  and  behavior  definitions  should  begin  in  the  first  column  of  the  file. 

•  Don't  put  any  extra  spaces  between  definition  keywords  (e.g.,  use  “when  receiving" 
not  "when  receiving”. 

•  Always  put  the  function  name  on  the  same  line  as  the  word  “defun”  and  always  put 
the  message-pattern  of  a  behavior  definition  on  the  same  line  as  the  words  “when  re¬ 
ceiving”,  even  if  this  exceeds  80  characters. 

•  Always  terminate  the  line  that  begins  a  function  or  behavior  definition  with  a  <CR> 
or  <LF> 


5.  Window  management 


When  you’ve  finished  editing  functions  or  behaviors  in  a  file  you  will  probably  want  to  get  back 
to  the  window  containing  the  Lisp  session.  To  do  this  the  following  commands  are  useful: 


Function _ Binding  Action 

8witch-to-buffer  ‘X-b  Prompts  for  the  name  of  the  buffer  and  associates  it  srith  the  current 

window.  The  old  buffer  associated  with  this  window  merely  loses 

_ that  association:  it  b  not  erased  or  changed  in  any  way. _ 

delete-buffer  ‘X-d  Removes  the  current  window  from  the  screen  and  gives  it's  space  to  its 

neighbor  below  (or  above).  You  do  not  lose  the  buffer  associated  with 

_ the  window,  it  just  is  not  visible. _ 

delete-other- windows  ‘X-1  Deletes  all  windows  but  the  one  you  are  in,  which  now  takes  up  the 

whole  screen.  The  buffers  associated  with  the  other  windows  are  not 
lost. 

next-window  'X-n  Switches  to  the  window  (and  associated  buffer)  that  is  below  the 

_ current  window. _ 

previous-window  ‘X-p  Switches  to  the  window  (and  associated  buffer)  that  is  above  the 

current  window. 


ROSS-Emacs  commands  for  window  maintenance 
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There  are  several  ways  to  use  these  commands  to  get  back  to  Lisp  and  ROSS:  (i)  use  'X*b  and 
respond  "lisp"  to  the  prompt,  to  put  Lisp  in  the  window  you  are  now  in  (thus  losing  the  edited 
file);  (ii)  use  'X-n  or  ‘X*p  to  get  to  the  previous  (higher)  or  next  (lower)  window  on  your  screen, 
repeating  until  you  are  in  the  Lisp  window;  (iii)  use  ‘X*d  to  delete  the  current  (i.e.,  edit)  window 
then  go  to  the  Lisp  w  adow.  The  latter  method  is  often  preferable  if  you  find  your  screen  becom¬ 
ing  cluttered  with  windows  associated  with  previously  edited  files.  It  is  a  good  practice  to  get  rid 
of  unneeded  windows. 


6.  Evaluating  things 


One  important  thing  you’ll  want  to  do  is  evaluate  pieces  of  code  you  are  pointing  at.  If  you  are 
in  a  window  associated  with  a  ROSS  session  a  <CR>  can  do  this,  but  in  any  other  window 
<CR>  just  inserts  a  new  line  (the  normal  Emacs  action  for  <CR>).  There  are  several  special 
functions  that  allow  you  to  evaluate  what  you  are  pointing  to  in  any  window. 


Function 

Rindinn 

Action 

sap-thing 

ESC-t 

Marks  the  "thing”  currently  being  pointed  at,  submits  it  to  Lisp  where 
it  is  evaluated,  then  returns  to  the  original  point  in  the  current  buffer. 
Exactly  what  "thing”  is  pointed  at  is  determined  by  the  prefix  argu¬ 
ments  the  user  supplies  to  sap-thing.  If  no  prefix  is  supplied  then  the 
current  atom  is  evaluated;  if  one  argument  (‘-U)  is  supplied  then  the 
smallest  (first-level)  list  embedding  the  cursor  b  evaluated;  if  two  argu¬ 
ments  (*-U  ‘-U)  are  supplied  then  the  second  smallest  (second-level)  list 
embedding  the  cursor  b  evaluated,  and  so  on.  If  more  arguments  are 
supplied  than  there  are  embedding  Ibte,  an  error  b  signalled.  Zap-thing 
b  the  most  general  evaluation  function. 

xap-expr 

ESC-e 

Marks  the  Ibt  s-expression  currently  being  pointed  at,  submits  it  to  Lisp 
where  it  b  evaluated,  then  returns  to  the  original  point  in  the  current 
buffer.  Equivalent  to  '-U  ESC-t. 

lap-message 

ESC-m 

Marks  the  region  around  the  cursor  that  begins  with  any  message  form 
"(ask"  or  "(tell”,  submits  it  to  Lisp  for  evaluation,  then  returns. 

lap-defun 

ESC-d 

Marks  the  current  function  defining  form,  submits  it  to  Lbp,  and  stays 
there. 

tap-defun-stay 

ESC-s 

Marks  the  current  function  defining  form,  submits  it  to  Lbp,  then  re¬ 
turns  to  the  original  point  in  the  current  buffer. 

tap-string 

ESC-y 

Prompts  the  user  for  a  Lisp  or  ROSS  form,  then  submits  the  form  to 
ROSS,  where  its  value  b  printed,  and  finally  returns  to  the  original 
point  in  the  current  buffer. 

ROSS-Emacs  commands  for  evaluating 


In  general  these  functions  can  be  used  in  any  window  (not  just  “lisp”),  providing  Emacs  under¬ 
stands  that  the  code  in  the  window  is  Lisp  or  ROSS  code. 


•  It  will  understand  this  only  if  the  file  has  the  extention  type  “.I”.  So  make  sure  you 
use  this  extention  if  you  want  to  be  able  evaluate,  edit  or  compile  code  via  Emacs. 

When  evaluating  things  just  make  sure  the  cursor  is  in  the  window  containing  the  code  you  want 

to  evaluate  and  is  pointing  to  the  exact  Lisp  or  ROSS  expression  you  are  interested  in.  Generally, 

this  means  pointing  at  a  top-level  element  in  the  target  list-structure.  If  you  point  to  an  element 

in  an  embedded  list,  then  that  list,  not  the  inclusive  target  list  will  get  evaluated. 

Once  you  are  pointing  at  the  right  expression,  just  give  the  correct  keystroke  sequence.  The 
result  of  evaluation  should  appear  in  the  Lisp  window,  regardless  of  whether  the  evaluated  code 
was  in  that  window  or  some  other  one. 


7.  Compiling  cod* 


The  current  facility  enables  the  user  to  interactively  compile  function  (not  behavior)  definitions  as 
well  as  interactively  modify  interpreted  ones.  This  can  be  especially  useful  when  speed  is  essen- 


Function  Bindin 


compile-function  ESC-i 


compile-file  ESC-o 


Action 


Takes  the  function  definition  currently  pointed  at,  submits  it  to  the  Lisp 
compiler,  lisst,  then  loads  the  resulting  “.o”  file  into  Lisp,  Anally  return¬ 
ing  you  to  where  you  started. 


Like  compile-function,  except  the  whole  file  cunently  being  pointed  at  is 
written,  recompiled,  and  loaded  into  Li 
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8.  Defining  ROSS  Bystems  and  learehlng  them 


As  a  ROSS  qrsteni  gets  larger  you  may  lose  track  of  where  various  functions,  objects  and 
behaviors  are.  This  may  make  it  difficult  to  rapidly  access  pieces  of  code,  for  example  when  edit- 
funetion  (see  Section  4)  asks  you  where  a  function  is.  There  is  a  simple  facility  that  allows  Emacs 
to  construct  a  “map"  of  your  system,  obviating  the  need  for  yon  to  have  one. 


Function 

Bindintc  Action 

load- rose- system 

Prompts  you  for  a  file  name,  which  should  contain  the  names  of  each  of 

the  files  in  your  ROSS  system.  The  names  diould  be  one  to  a  line,  be¬ 
ginning  in  the  first  column.  If  you  envision  loading  the  system  from 
various  directories,  each  file  should  be  specified  by  full  absolute  path¬ 
names.  A  ROSS  system  must  be  loaded  using  this  function  before  any 
of  the  following  functions  will  work. _ 


re-tag-ross-system  — 

Goes  through  each  of  the  files  in  a  loaded  ROSS  system  and  remembers 
the  location  of  each  function,  macro,  variable,  object,  and  behavior  in 
the  system.  After  this,  edit-funetioa  and  tdit-btkamor  will  never  have 
to  ask  you  where  a  function  or  behavior  is  located. 

whereis-function  - 

Prompts  for  the  name  of  a  function  and  returns  the  name  of  the  file 
where  it  is  located.  Will  work  for  defmacros,  and  defvars  as  well  as  de- 
funa  Returns  its  answer  much  more  rapidly  if  it  has  rememebered  (c.g., 
via  re-tag-ross-system)  where  the  function  is. 

whereis-behavior 

Like  mhereio-fnnetion.  except  it  nromots  for  an  obieet  and  behavior. 

ROSS'Emacs  commands  for  defining  and  searching  a  ROSS  system 
The  recommended  procedure  is  to  re-ta^  your  ROSS  system  periodically.  This  task  may  take  a 
minute  or  two,  but  it  greatly  speeds  op  the  operation  of  edit-funetion,  edit-behavior,  wkereit- 
funetion,  and  whereie-behavior.  Re-tag  whenever  you  have  made  substantial  additions  to  the  sys¬ 
tem,  or  have  moved  things  from  one  file  to  another.  If  you  don’t  tag  your  system,  and  then  ask 
Emacs  where  a  certain  function  is,  it  may  have  to  do  a  search  through  all  your  system  files  to 
find  it.  When  you  get  back  from  lunch  it  might  be  done. 


0.  Moving  siround  ntrueturea 


In  addition  to  the  normal  Emacs  commands  for  moving  forward  and  backward  by  character  or  by 
line,  there  are  some  commands  that  are  especially  useful  for  moving  around  Lisp  or  ROSS  exprev 
sions  and  manipulating  them. 
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_ Function _ BindinK _ Action _ 

forward-word  ••  Move  dot  forward  to  the  end  of  a  word.  If  not  currently  in  the  middle 

of  a  word,  skip  all  intervening  punctuation.  Then  skip  over  the  word, 
leaving  dot  positioned  after  the  last  character  of  the  word.  A  word  is  a 
sequence  of  alphanumerics.  Note:  this  is  normally  bound  to  ESC-f  in 

_ Emacs.  If  you  envision  using  it  frequently,  rebind  it  to  something. _ 

backward-word  ~  If  in  the  middle  of  a  word,  go  to  the  beginning  of  that  word,  otherwise 

go  to  the  beginning  of  the  preceding  word.  A  word  is  a  sequence  of  al¬ 
phanumerics.  Note:  this  is  normally  bound  to  ESC-b  in  Emacs.  If  you 

_ envision  using  it  frequently,  rebind  it  to  something. _ 

delete-previous-word  —  If  not  in  the  middle  of  a  word,  delete  characters  backwards  (to  the  left) 

until  a  word  is  found.  Then  delete  the  word  to  the  left  of  dot.  A 
word  is  a  sequence  of  alphanumerics.  Note:  this  is  normally  bound  to 
ESC-h  in  Emacs.  If  you  envision  using  it  frequently,  rebind  it  to  some- 
_ thing. _ 

delete-next-word  ESC-D  Delete  characters  forward  from  dot  until  the  next  end  of  a  word.  If 

dot  is  currently  not  in  a  word,  all  punctuation  up  to  the  beginning  of 

_ the  word  is  deleted  as  well  as  the  word. _ 

backward-higher-paren  ESC-(  Moves  backwards  to  a  higher  opening  parenthesis  that  is  unmatched  by 

any  closing  parenthesis  before  the  current  position  of  the  cursor.  Exactly 
which  such  parenthesis  is  determined  by  the  number  of  prefix  arguments 
given  to  the  function.  If  lero  or  one  argument  is  given  (‘-U)  the  cursor 
goes  to  the  first  unmatched  parenthesis;  that  is,  the  "(”  of  the  first-level 
list  embedding  the  cursor.  If  two  arguments  are  given  ('-U  '-U)  the 
cursor  goes  to  the  opening  parenthesis  of  the  second-level  list  embedding 
the  cursor,  and  so  on.  If  more  prefixes  are  given  than  there  are  lists 
embedding  the  cursor,  the  cursor  goes  to  the  opening  parenthesis  of  the 

_ top-level  list,  and  an  error  is  signaled. _ 

forward-higher-paren  ESC-) _ Analogous  to  backward-higher-paren,  but  moves  forward  in  the  file. 

newline-and-indent  LINEFEED  Insert  a  newline,  just  as  typing  <CR>  does,  but  then  insert  enough 

tabs  and  spaces  so  that  the  newly  created  line  has  the  same  indenta¬ 
tion  as  the  old  one  had.  This  is  quite  useful  when  you’re  typing  in  a 

_ block  of  program  text,  all  at  the  same  indentation  level. _ 

re-indentrline  TAB  Causes  the  line  you  are  on  to  shift  left  or  right  so  that  the  expressions 

on  it  will  be  aligned  correctly  with  the  ones  on  the  previous  line.  In  oth- 

_ er  words,  it  pretty-prints  the  line. _ 

mark-list  —  Causes  the  list  you  are  pointing  at  to  be  marked  (e.;.,  so  it  can  be  sub¬ 

sequently  killed,  copied,  etc).  Exactly  which  of  the  embedded  lists  gets 
marked  is  determined  by  the  number  of  prefix  arguments  you  supply, 
according  to  the  logic  of  boekvori-kigker-paren. 


ROSS-Emacs  commands  for  moving  around  structures 


10.  Retrieving  name*  of  entitle* 


There  are  a  few  commands  which  return  the  names  of  entities  currently  being  pointed  at.  These 
are  mainly  used  by  other  functions,  hence  have  no  key  bindings. 


Function 

Bindinc  Action 

current-function 

If  pointing  at  a  function  defining  form  (i.e.,  one  beginning  with  “(def), 
returns  the  function  name.  If  not,  returns  the  name  of  the  nearest  func¬ 
tion  defining  form,  searching  back  up  through  the  buffer. 

current-object 

Returns  the  name  of  the  object  sent  the  message  now  being  pointed  at 
or  nearest  the  cursor. 

current- behavior 

Returns  the  pattern  of  the  behavior  definition  (“when  receiving’’)  now 
being  pointed  at  or  nearest  the  cursor. 

ROSS'Emacs  commands  for  retrieving  names 


11.  Help  and  Documentation 


There  are  a  couple  of  functions  for  on-line  help  with  ROSS  in  general  and  the  ROSS-Emacs  facili¬ 
ty  in  particular. 


Function 

Binding 

Action 

ross-emacs-help 

ESC-h 

Prints  information  on  ROSS-Emacs  commands  in  the  Help  window. 

ross-manual 

Prompts  user  for  the  name  of  a  ROSS  command,  then  prints  the  ROSS 
manual  documentation  for  that  command  in  a  window.  The  command 
should  be  entered  in  upper  case.  The  whole  command  need  not  be  en¬ 
tered.  just  enough  of  the  beginning  to  provide  unique  identification. 

ROSS-Emacs  commands  for  help  and  documentation 


IS.  Getting  started 


To  run  the  facility  you  need  to  have  an  Emacs  initialization  file  that  loads  the  ROSS-Emacs  utili¬ 
ties.  A  reasonable  initialization  file  to  begin  with  is  /a/ftpross /emacs _pro.  Copy  it  into  a  file 
named  ‘‘.emac8_pro"  (note  the  in  your  home  directory.  The  actual  mlisp  (mocklisp)  code 
that  implements  the  ROSS-Emacs  facility  can  be  found  in  /a/ftpross/ross-emacs.ml  on  rand-unix. 
Finally,  /a/ftpross/ross-emacs  is  a  simple  shell  file  for  initiating  ROSS  under  Emacs.  If  you  exe¬ 
cute  this  file  you  will  find  yourself  in  an  Emacs  session,  with  ROSS  running  in  one  window. 


To  vac  the  ROSS*Ein»cs  facility,  the  naer  moat  have  aeeeaa  to  an  extenaible  verawa  of  Emaca, 
anch  aa  Unix  Emaca  by  Jamea  Gosling.  Unix  Emaca  is  available  f/om  Uaipieaa  Softwan,  for  a  fee. 
Yon  might  also  be  able  to  get  it  for  free  from  CMU,  if  yon’re  Incky. 

IS.  RafwnDeaa 
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